Separating how-to guides ('gathering info' sections) from reference documents #792
Conversation
ahouseholder
added
the
content/representation
|
Please consider which/whether this PR is intended to address:
If it is, update the resolution keywords in the description accordingly. |
|
moving the "gathering information" sections to the how to instead of reference like this makes sense to me. |
ahouseholder
left a comment
ahouseholder
left a comment
There was a problem hiding this comment.
I like the split of Gathering Info off into the HowTo section of the docs. That part is fine.
- What I'm left with though is that in
docs/reference/decision_points/*there are (at least as of the current commit) no breadcrumbs pointing from the reference doc to the corresponding howto doc.
I suggest leaving something akin to the following behind in each of the relevant reference pages.
!!! tip Gathering Information about Foo
See this [HowTo](link) for advice on gathering information about the Foo decision point.Adjust wording to taste, I'm mostly concerned that (a) there is a link to it, and (b) it's probably in a call-out.
- In the new "HowTo" pages, I think it would make sense to also include the current version example block somewhere near the top of the page.
python exec="true" idprefix=""
from ssvc.decision_points.ssvc.automatable import LATEST
from ssvc.doc_helpers import example_block
print(example_block(LATEST))Other than that I can't think of anything else at the moment.
|
I had previously commented:
After conversations with @sei-renae, I believe this PR, once complete, would resolve #723 and #537, while leaving #522 and #362 as future work. I added closing keywords to the PR description consistent with this observation. |
sei-renae
requested review from
cgyarbrough,
j--- and
sei-vsarvepalli
as code owners
ahouseholder
left a comment
ahouseholder
left a comment
There was a problem hiding this comment.
I made a few fixes directly before doing this review. There are still a few changes I'd like to see before we finish this per comments that follow.
sei-vsarvepalli
left a comment
sei-vsarvepalli
left a comment
There was a problem hiding this comment.
All markdown changes checkout fine.
ahouseholder
left a comment
ahouseholder
left a comment
There was a problem hiding this comment.
A couple previous comments remain unresolved, and I had a couple new ones on this revision. In particular, the sentence fragment in Human Impact is a blocker for merging.
|
@ahouseholder I think I got it all this time |
4 participants
Gathering Info...sections of Decision Point reference pages #537